<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Display Matrix
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot018.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot020.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc37">4.1</A>&nbsp;&nbsp;Display Matrix</H2><UL>
<LI><A HREF="umsroot019.html#toc20">Invoking display matrix tool interactively</A>
</UL>

<A NAME="displaymat"></A>
This tool provides a method to display the values of terms in a matrix
form. It is particularly useful because it can display the attributes of an
attributed variable.<SUP><A NAME="text1" HREF="umsroot018.html#note1">1</A></SUP>
The predicate which invokes the display matrix is considered a no-op
in the tty-based ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP><SUP><A NAME="text2" HREF="umsroot018.html#note2">2</A></SUP>, and so the same code can be run without
modification from either <TT>eclipse</TT> or <TT>tkeclipse</TT>, though
the matrix display is only presented to the user in the latter.<BR>
<BR>
This tool is invoked using either the
<A HREF="../bips/kernel/debug/make_display_matrix-2.html"><B>make_display_matrix/2</B></A><A NAME="@default133"></A>
predicate or the
<A HREF="../bips/kernel/debug/make_display_matrix-5.html"><B>make_display_matrix/5</B></A><A NAME="@default134"></A>
predicate.
Adding a call to one of these predicates should be the only change you need
to make to your code.
For example, in the following fragment of a N-queens program, only one
extra line has been added to invoke a display matrix:

<PRE CLASS="verbatim">
   queens(N, List) :-
       length(List, N),
       List :: 1..N,
       make_display_matrix(List/0, queens),
       % sets up a matrix with all variables in 1 row. This is the only
       % extra goal that has to be added to enable monitoring
       alldistinct(List),
       constrain_queens(List),
       labeling(List).
</PRE>
<BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
<DIV CLASS="center">
<IMG SRC="umsroot002.gif">
</DIV>
<BR>
<BR>
<DIV CLASS="center">Figure 4.1: Display Matrix Tool for 4-Queens (Initial)</DIV><BR>
<BR>

<A NAME="dismat"></A>
<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
<BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
<DIV CLASS="center">
<IMG SRC="umsroot003.gif">
</DIV>
<BR>
<BR>
<DIV CLASS="center">Figure 4.2: Display Matrix Tool for 4-Queens (During execution)</DIV><BR>
<BR>

<A NAME="dismat2"></A>
<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
Figures&nbsp;<A HREF="#dismat">4.1</A> and <A HREF="#dismat2">4.2</A> show the tool
invoked with the example N-Queens programs for 4 Queens, at the start
initially and during the execution of the program. The name of the display
window is specified by the second argument of
<A HREF="../bips/kernel/debug/make_display_matrix-2.html"><B>make_display_matrix/2</B></A><A NAME="@default135"></A>,
along with the module it is in. The values of the terms are shown in the
matrix, which can be one dimensional (as in this case), or two
dimensional. Spy points can be set on each individual cell of the matrix
so that execution will stop when the cell is updated. The matrix can be
killed using the `Kill display' button. Left-clicking on a cell will bring
up a menu which shows the current and previous value of the term in the
cell (the current value is shown because the space available in the cell
may be too small to fully display the term), and allows the user to inspect
the term using the inspector. <BR>
<BR>
Note that the display matrix can be used independently of, or in conjunction
with, the tracer. Multiple display matrices can be created to view
different terms.<BR>
<BR>
The following predicates are available in conjunction with the display
matrix:<BR>
<BR>
<BR>
<B>make_display_matrix(+Terms, +Name)</B> <BR>
<B>make_display_matrix(+Terms, +Prio, +Type, +CondList, +Name)</B>
<A NAME="@default136"></A>
<A NAME="@default137"></A><BR>
<BR>
These
predicates create a display matrix of terms that can be monitored under
TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. The two argument form is a simplification of the five argument
form, with defaults settings for the extra arguments. Terms is a list or
array of terms to be displayed. A List can be specified in the form List/N,
where N is the number of elements per row of the matrix. If N is 0, then
the list will be displayed in one row (it could also be omitted in this
case). The extra arguments are used to control how the display is updated.<BR>
<BR>
The terms are monitored by placing a demon suspension on the variables
 in each term. When a demon wakes, the new value of the term it is
 associated with is sent to the display matrix (and possibly updated,
 depending on the interactive settings on the matrix). When the new 
 value is backtracked, the old value is sent to the display matrix.
 The other arguments in this predicate is used to control when the
 demon wakes, and what sort of information is monitored. Prio is the
 priority that the demon should be suspended at, Type is designed to
 specify the attributes that is being monitored (currently all 
 attributes are monitored, and Type is a dummy argument), CondList is 
 the suspension list that the demon should be added to. Depending on
 these arguments, the level of monitoring can be controlled. Note that
 it is possible for the display matrix to show values that are out of
 date because the change was not monitored. <BR>
<BR>
The display matrix will be removed on backtracking. However, it will 
 not be removed if make_display_matrix has been
 cut &ndash; <CODE>kill_display_matrix/1</CODE> can be used to explicitly remove the
 matrix in this case.<BR>
<BR>
<BR>
<B>kill_display_matrix(+Name)</B>
<A NAME="@default138"></A><BR>
<BR>
This predicate destroys an existing
 display matrix. Name is an atomic term which identifies the matrix.<BR>
<BR>
Destroys an existing display matrix. The display matrix is removed
 from being displayed.<BR>
<BR>
<A NAME="toc20"></A>
<H3 CLASS="subsection"><A NAME="htoc38">4.1.1</A>&nbsp;&nbsp;Invoking display matrix tool interactively</H3>
Display matricies can be created interactively when a program is
executing, if the program is being debugged with the tracer tool. The user
can select terms that are to be observed by a display matrix while at a
debug port. This can be done from the inspector, the tracer, and the delay
goal tools. See the online help files (available from the help menu of
TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>) for more details.<BR>
<BR>
<HR>
<A HREF="umsroot018.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot020.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
